// Copyright (c) 2010, Anthony Cassidy
// All rights reserved.
// 
// Redistribution and use in source and binary forms, with or without modification, are 
// permitted provided that the following conditions are met:
// 
//     * Redistributions of source code must retain the above copyright notice, this list 
//         of conditions and the following disclaimer.
//     * Redistributions in binary form must reproduce the above copyright notice, this 
//         list of conditions and the following disclaimer in the documentation and/or 
//         other materials provided with the distribution.
//     * Neither the name of the AntsAdventureGameCreator nor the names of its contributors 
//         may be used to endorse or promote products derived from this software without 
//         specific prior written permission.
// 
// 
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY 
// EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 
// OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT 
// SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 
// THE POSSIBILITY OF SUCH DAMAGE.
#include "ROOMDECLARATION.h"

/*!
@page Example3
<h1>Example 3 - Adding Event Handlers</h1> 

<h2>Summary</h2>
This example shows you how to declare a room, add specify
the IEventHandlers for that room.

<h2>Steps</h2>
The engine is event based: Rather than you calling it, it calls you
...via nine different 'event handlers'. You will need to implement
these nine event handlers for each Room
that you have. When a particular room is active
only the event handlers for that room are called.
The currently active room is
set by calling the Room::MakeRoomActive method with the name
of the Room you want to switch to.
<br>
Before a room can be switched
to, it must be declared as a class,
and registered with the RoomRegistry.
This can be done manually using standard c++ code,
but the easiest way is via
the ROOMDECLARATION() macro.
Once you register a room
using this macro, you will need
to provide an implementation
of the IEventHandlers
for that Room,
otherwise the executable won't link.

<ol>

<li><b>To declare the room add a ROOMDECLARATION() in main.cpp</b>

@code
ROOMDECLARATION(MyFirstRoom)
@endcode

<img src="Example3_1.png">
Rooms are defined using the ROOMDECLARATION() define.
For example:
@code
ROOMDECLARATION("RoomName");
@endcode

The string parameter is used for two things
One is the folder to look in to find the graphics
and the other is as a way to identify the room
in the API. For example if you want to switch to a room declared
with the name "Bathroom", then you would use the api call.
Room::MakeRoomActive("Bathroom"); 

If you try to build now you will notice that you receive
many undefined reference errors.
<img src="Example3_2.png">
</li>

<li><b>Implement the EventHandlers for your room(s)</b><br>
If you want to see when each of the event handlers is called, you 
may want to check out the help page for IEventHandlers.
<br>
If you try to build now, the project should be free of errors.
<img src="Example3_3.png">
If the project doesn't compile, check to see that you have implemented
each event handler properly. All of them have a void return value, except
for IEventHandlers::OnDebugMenuExtension() which returns a QString return value.
</li>

<li><b>Run and Confirm that the event handlers are being called</b><br>
Run the exe, and choose "Switch to Room..." and browse to the
folder called "Example3".

Not much will happen because we haven't put much in the event handlers.
But you can confirm the event handlers are being called by
placing debug breakpoints on each implementation.
</li>

<li>
<img src="Example3_4.png">
If the breakpoints don't hit, a few things could have gone wrong:
- Make sure the Project is being built in Debug mode.
- Make sure you browsed to a folder named exactly the same as the name declared in ROOMDECLARATION()
</li>
</ol>
<br>
<br>
On to @ref Example4...
*/

